home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3c / libperfex.z / libperfex
Encoding:
Text File  |  2002-10-03  |  13.0 KB  |  199 lines
  1.  
  2.  
  3.  
  4. LLLLIIIIBBBBPPPPEEEERRRRFFFFEEEEXXXX((((3333CCCC))))                                                    LLLLIIIIBBBBPPPPEEEERRRRFFFFEEEEXXXX((((3333CCCC))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      lllliiiibbbbppppeeeerrrrffffeeeexxxx, ssssttttaaaarrrrtttt____ccccoooouuuunnnntttteeeerrrrssss, rrrreeeeaaaadddd____ccccoooouuuunnnntttteeeerrrrssss, pppprrrriiiinnnntttt____ccccoooouuuunnnntttteeeerrrrssss, pppprrrriiiinnnntttt____ccccoooossssttttssss,
  10.      llllooooaaaadddd____ccccoooossssttttssss - A procedural interface to processor event counters
  11.  
  12. CCCC SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.          iiiinnnntttt ssssttttaaaarrrrtttt____ccccoooouuuunnnntttteeeerrrrssss(((( iiiinnnntttt eeee0000,,,, iiiinnnntttt eeee1111 ))));;;;
  14.          iiiinnnntttt rrrreeeeaaaadddd____ccccoooouuuunnnntttteeeerrrrssss(((( iiiinnnntttt eeee0000,,,, lllloooonnnngggg lllloooonnnngggg ****cccc0000,,,, iiiinnnntttt eeee1111,,,, lllloooonnnngggg lllloooonnnngggg ****cccc1111))));;;;
  15.          iiiinnnntttt pppprrrriiiinnnntttt____ccccoooouuuunnnntttteeeerrrrssss(((( iiiinnnntttt eeee0000,,,, lllloooonnnngggg lllloooonnnngggg cccc0000,,,, iiiinnnntttt eeee1111,,,, lllloooonnnngggg lllloooonnnngggg cccc1111))));;;;
  16.          iiiinnnntttt pppprrrriiiinnnntttt____ccccoooossssttttssss(((( iiiinnnntttt eeee0000,,,, lllloooonnnngggg lllloooonnnngggg cccc0000,,,, iiiinnnntttt eeee1111,,,, lllloooonnnngggg lllloooonnnngggg cccc1111))));;;;
  17.          iiiinnnntttt llllooooaaaadddd____ccccoooossssttttssss((((cccchhhhaaaarrrr ****CCCCoooossssttttFFFFiiiilllleeeeNNNNaaaammmmeeee))));;;;
  18.  
  19.  
  20. FFFFOOOORRRRTTTTRRRRAAAANNNN SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  21.           IIIINNNNTTTTEEEEGGGGEEEERRRR****8888 cccc0000,,,, cccc1111
  22.           IIIINNNNTTTTEEEEGGGGEEEERRRR   eeee0000,,,, eeee1111
  23.           CCCCHHHHAAAARRRRAAAACCCCTTTTEEEERRRR((((****nnnn)))) CCCCoooossssttttFFFFiiiilllleeeeNNNNaaaammmmeeee
  24.           IIIINNNNTTTTEEEEGGGGEEEERRRR****4444 ffffuuuunnnnccccttttiiiioooonnnn ssssttttaaaarrrrtttt____ccccoooouuuunnnntttteeeerrrrssss(((( eeee0000,,,, eeee1111 ))))
  25.           IIIINNNNTTTTEEEEGGGGEEEERRRR****4444 ffffuuuunnnnccccttttiiiioooonnnn rrrreeeeaaaadddd____ccccoooouuuunnnntttteeeerrrrssss(((( eeee0000,,,, cccc0000,,,, eeee1111,,,, cccc1111 ))))
  26.           IIIINNNNTTTTEEEEGGGGEEEERRRR****4444 ffffuuuunnnnccccttttiiiioooonnnn pppprrrriiiinnnntttt____ccccoooouuuunnnntttteeeerrrrssss(((( eeee0000,,,, cccc0000,,,, eeee1111,,,, cccc1111 ))))
  27.           IIIINNNNTTTTEEEEGGGGEEEERRRR****4444 ffffuuuunnnnccccttttiiiioooonnnn pppprrrriiiinnnntttt____ccccoooossssttttssss(((( eeee0000,,,, cccc0000,,,, eeee1111,,,, cccc1111 ))))
  28.           IIIINNNNTTTTEEEEGGGGEEEERRRR****4444 ffffuuuunnnnccccttttiiiioooonnnn llllooooaaaadddd____ccccoooossssttttssss(((( CCCCoooossssttttFFFFiiiilllleeeeNNNNaaaammmmeeee ))))
  29.  
  30. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  31.      These routines provide simple access to the hardware event counters.  The
  32.      arguments eeee0000 and eeee1111 are iiiinnnntttt types specifying which events to count.  For
  33.      descriptions of the counters themselves, see the ppppeeeerrrrffffeeeexxxx(1) or the
  34.      rrrr11110000kkkk____ccccoooouuuunnnntttteeeerrrrssss(5) man page.
  35.  
  36.      The counts are returned in the lllloooonnnngggg lllloooonnnngggg arguments cccc0000 and cccc1111. The
  37.      pppprrrriiiinnnntttt____ccccoooouuuunnnntttteeeerrrrssss routine prints the counts to standard error.  Two events
  38.      which mmmmuuuusssstttt be counted on the same hardware counter will cause a
  39.      conflicting counters error. The arguments _e_0 and _e_1 can be overridden by
  40.      setting the environment variables TTTT5555____EEEEVVVVEEEENNNNTTTT0000 and TTTT5555____EEEEVVVVEEEENNNNTTTT1111.  Calls to
  41.      ssssttttaaaarrrrtttt____ccccoooouuuunnnntttteeeerrrrssss implicitly zero out the internal software counters before
  42.      starting them, while rrrreeeeaaaadddd____ccccoooouuuunnnntttteeeerrrrssss implicitly stops the counters after
  43.      reading them. Thus if you want to accumulate counts over multiple
  44.      start/read calls, you must save out the counts and do the accumulation
  45.      yourself. Each of these incurs a typical system call overhead which can
  46.      amount to a few hundred microseconds per start/stop call pair. The
  47.      pppprrrriiiinnnntttt____ccccoooouuuunnnntttteeeerrrrssss procedure is just a formatting convenience and has no
  48.      effect on the state of the counters.
  49.  
  50. TTTTIIIIMMMMEEEE EEEESSSSTTTTIIIIMMMMAAAATTTTEEEESSSS AAAANNNNDDDD CCCCOOOOSSSSTTTT TTTTAAAABBBBLLLLEEEESSSS
  51.      The pppprrrriiiinnnntttt____ccccoooossssttttssss routine prints the counts together with approximate time
  52.      estimates as described for ppppeeeerrrrffffeeeexxxx.  The llllooooaaaadddd____ccccoooossssttttssss procedure allows a
  53.      cost table to be loaded from a file.  Cost ranges reflect both the width
  54.      of the cost distribution and uncertainty in the degree of overlap.  Costs
  55.      for different events are not exclusive due to the overlap of one type of
  56.      event with others.  By default a table of costs for each event
  57.      appropriate to the host system is used.  If the file ////eeeettttcccc////ppppeeeerrrrffffeeeexxxx....ccccoooossssttttssss is
  58.      present, it is used instead. If a table is loaded using load_costs, it is
  59.      used instead. Partial tables may be used; the remaining entries taking
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. LLLLIIIIBBBBPPPPEEEERRRRFFFFEEEEXXXX((((3333CCCC))))                                                    LLLLIIIIBBBBPPPPEEEERRRRFFFFEEEEXXXX((((3333CCCC))))
  71.  
  72.  
  73.  
  74.      the appropriate default values. The format of the cost table and how to
  75.      dump the default cost table for the current system are described in the
  76.      perfex manpage.
  77.  
  78. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  79.      Normal completion returns a positive integer, the ggggeeeennnneeeerrrraaaattttiiiioooonnnn nnnnuuuummmmbbbbeeeerrrr.
  80.      Negative return values signal an error.  The underlying operating system
  81.      counter interface may produce other errors.  Among these are indications
  82.      that the counter resource is in use, possibly because of monitoring by
  83.      another user on the system (with root privileges) in system mode.  The
  84.      generation numbers increment on a per-process basis each time the
  85.      counters are enabled or stopped.  Because the counters may have been used
  86.      by a supervisor-privilege process after being enabled by the user with
  87.      start_counters, but before being read by read_counters, all correct uses
  88.      of the interface must check that the generation number returned by
  89.      read_counters matches the generation number from the corresponding
  90.      start_counters, for each process.  For example, To collect instruction
  91.      and data scache miss counts on a program normally executed by
  92.      int e0,e1
  93.      long long c0,c1;
  94.      int gen_start, gen_read
  95.  
  96.      /* ... set e0 and e1  ... */
  97.  
  98.      if((gen_start=start_counters(e0,e1)) < 0) {
  99.          perror("start_counters");
  100.        }
  101.  
  102.      /* user code */
  103.  
  104.      if((gen_read=read_counters(e0,&c0,e1,&c1))<0) {
  105.         perror("read_counters");
  106.        }
  107.  
  108.      if(gen_read != gen_start) {
  109.         perror("lost counters!, aborting...");
  110.         exit(1);
  111.        }
  112.  
  113.      /* do something with c0,c1 */
  114.      illustrates correct use. Counter measurements are typically not precisely
  115.      reproducible for most events.  For example, counts of cache misses depend
  116.      on the change in the cache population due to other processes when the
  117.      target process is not running.  Invalidation and intervention counts may
  118.      depend on the temporal ordering of memory accesses by different
  119.      processors, which is not guaranteed.  Issued instruction counts depend on
  120.      the R10000's dynamic scheduling of instructions, which in turn can depend
  121.      on the pattern of instruction cache misses.  Since the cache misses are
  122.      affected by the runtime environment as noted above, this count is also
  123.      not precisely reproducible.  In almost all cases, however, while the
  124.      exact count may not be reproducible, the amount of time attributable to
  125.      any fluctuations is a tiny fraction of the execution time.  Conversely,
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. LLLLIIIIBBBBPPPPEEEERRRRFFFFEEEEXXXX((((3333CCCC))))                                                    LLLLIIIIBBBBPPPPEEEERRRRFFFFEEEEXXXX((((3333CCCC))))
  137.  
  138.  
  139.  
  140.      any event which accounts for an important fraction of the execution time
  141.      will have a count with small relative fluctuations from run to run.
  142.  
  143. RRRREEEESSSSTTTTRRRRIIIICCCCTTTTIIIIOOOONNNNSSSS
  144.      This interface is not reentrant or (pthread) thread-safe.  The
  145.      start_counters, read_counters, print_counters and print_costs, routines
  146.      can be called by individual sproc threads.  However there is only
  147.      provision for a single global cost table, so load_costs should be called
  148.      only in a sequential region, and that cost table must be applied to the
  149.      counts from all threads.
  150.  
  151. FFFFIIIILLLLEEEESSSS
  152.      ////uuuussssrrrr////lllliiiibbbb////lllliiiibbbbppppeeeerrrrffffeeeexxxx....ssssoooo ////uuuussssrrrr////lllliiiibbbb33332222////lllliiiibbbbppppeeeerrrrffffeeeexxxx....ssssoooo ////uuuussssrrrr////lllliiiibbbb66664444////lllliiiibbbbppppeeeerrrrffffeeeexxxx....ssssoooo
  153.  
  154. DDDDEEEEPPPPEEEENNNNDDDDEEEENNNNCCCCIIIIEEEESSSS
  155.      These procedures are only available on systems with hardware performance
  156.      counters (systems with R10000 or R12000 processors).  Use on systems with
  157.      mixed processor types will have undefined results in systems with mixed
  158.      processor types.
  159.  
  160.      Manipulating the counters with these routines and simultaneously through
  161.      ppppeeeerrrrffffeeeexxxx or the OS counter interface ioctl procedures can produce an error
  162.      if, for example, the counters are enabled twice without being released in
  163.      the interim.
  164.  
  165. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  166.      ppppeeeerrrrffffeeeexxxx(1), rrrr11110000kkkk____ccccoooouuuunnnntttteeeerrrrssss(5), aaaabbbbiiii(5), mmmmiiiippppssss4444(5), mmmmiiiippppssss3333(5)
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.